<!-- 文档分类: OPS-MAN-021 | 阶段: 运维 | 原路径: docs/指南/opencode-任务编排经验.md -->
OpenCode 任务编排机制学习记录#
日期： 2026-05-19
来源： /home/kodehu03/Downloads/opencode-dev.zip
OpenCode 在任务处理上的优点#
plan与build是两个独立主代理，分析与执行不混用。task()会创建真实子会话，不是简单提示词封装。- 后台任务是一等能力：
background=true、task_status、轮询、等待、取消都完整支持。 - 任务状态可持久化，并可通过
task_id恢复与续跑。 - 会话状态显式建模（
idle/busy/retry），编排更可控。 - 返回格式可机读（
<task_result>/<task_error>），便于 UI 与自动化处理。 - 子任务结果会在主线程空闲时再回注，避免输出交错与上下文冲突。
关键参考文件#
- agent.ts
- task.ts
- task_status.ts
- background/job.ts
- session/run-state.ts
- session/status.ts
- session/processor.ts
- session/retry.ts
- plan.ts
对 KHY 的迁移建议#
1. 把“任务”做成真实对象#
对于长任务，统一抽象为可追踪实体，至少包含：
- task id
- state
- progress
- output
- cancel
- resume
2. 严格分离规划与执行#
OpenCode 的 plan 默认只读，审批后再切回 build 执行。
KHY 应保持同样边界，避免计划阶段误改代码。
3. 显式状态流转#
把 busy / idle / retry 作为会话级状态，并在 CLI 与页面可视化展示。
4. 空闲时回注结果#
后台任务完成后，不应立即抢占主会话输出；应在主会话空闲时回注，减少“半截回复”和上下文错位。
5. 结果保持结构化#
任务结果应始终提供结构化字段，而不是只返回自然语言，便于后续自动编排和前端渲染。
6. 强化持久化与恢复#
计划、后台任务、多步骤流程都应支持跨会话恢复，避免中断后全量重来。
7. 重试策略统一化#
重试应记录原因、下一次时间点、可执行动作，不应散落在各处做临时处理。
KHY 落地优先级#
- 任务注册表 + task id + 状态查询 API
- 后台任务执行与
task_status轮询/等待 - 会话级
busy/idle/retry状态机 plan/build审批边界- 主线程空闲后回注机制
- 任务持久化与断点恢复
- 统一重试策略与元数据
结论#
如果 KHY 的目标是“让系统自己把复杂问题做完”，核心不是继续堆提示词，而是：
把每一个长任务都变成可跟踪、可恢复、可取消、可重试的会话化执行单元。
团队执行任务拆解（P0 / P1 / P2）#
P0（必须先完成，1-2 周）#
| 优先级 | 任务 | 负责人（建议） | 交付物 | 验收标准 |
|---|---|---|---|---|
| P0 | 任务注册表与状态 API（task id / state / progress / output） | Backend Owner | taskStore + 查询接口 + CLI 展示 | 可创建任务、查询任务、状态可追踪 |
| P0 | 后台任务执行与 task_status（轮询 + wait + timeout） | Backend Owner | 后台执行器 + task_status 命令 | 后台任务可启动、轮询、超时返回清晰 |
| P0 | 会话状态机（busy/idle/retry） | Runtime Owner | 会话运行态服务 + 状态事件 | 并发冲突可阻止，状态可观察 |
| P0 | plan/build 审批边界固化 | CLI Owner | plan-only 只读约束 + 审批切换逻辑 | plan 阶段无法写入非计划文件 |
P1（稳定性与体验增强，2-4 周）#
| 优先级 | 任务 | 负责人（建议） | 交付物 | 验收标准 |
|---|---|---|---|---|
| P1 | 主线程空闲后回注（resume-on-idle） | Runtime Owner | 回注调度器 + 状态监听 | 无“半截回复”、无输出重叠 |
| P1 | 任务持久化与断点恢复 | Backend Owner | 任务快照存储 + 恢复入口 | 进程重启后可继续任务 |
| P1 | 结构化任务输出协议 | Backend + Frontend | 统一输出 schema（result/error/progress） | CLI 与前端可稳定渲染同一数据 |
| P1 | 取消链路（父任务取消联动子任务） | Runtime Owner | 取消传播机制 | 取消父任务时子任务全部终止 |
P2（可运营与可扩展，4 周+）#
| 优先级 | 任务 | 负责人（建议） | 交付物 | 验收标准 |
|---|---|---|---|---|
| P2 | 统一重试策略中心（原因、next、action） | Gateway Owner | retry policy 模块 + 指标 | 重试行为一致、可观测 |
| P2 | 子代理权限继承与隔离强化 | Security Owner | 权限推导器 + 白名单策略 | 子任务不越权，误用率下降 |
| P2 | 任务质量看板（成功率、时延、失败原因） | SRE/Observability Owner | 监控报表 + 趋势图 | 能按任务类型定位瓶颈 |
| P2 | 任务模板库（常见任务标准化） | Product + AI Owner | 任务模板配置 + 引导文案 | 新任务接入成本下降 |
里程碑建议#
- M1：完成 P0，打通“可追踪后台任务”闭环。
- M2：完成 P1，解决并发输出混乱与中断恢复问题。
- M3：完成 P2，形成可运营、可治理的任务系统。
分工提示#
- Backend Owner：任务数据结构、持久化、状态 API。
- Runtime Owner：执行循环、状态机、取消与回注。
- CLI Owner：命令入口、状态展示、交互文案。
- Frontend Owner：任务可视化面板与状态追踪。
- Security Owner：权限模型、越权防护。
- SRE Owner：可观测性、告警与容量指标。